package com.ruoyi.tzai.service;

import java.util.List;
import com.ruoyi.tzai.domain.ApiKeyPool;

/**
 * API Key池Service接口
 * 
 * @author tzai
 * @date 2025-11-12
 */
public interface IApiKeyPoolService 
{
    /**
     * 查询API Key池
     * 
     * @param keyId API Key池主键
     * @return API Key池
     */
    public ApiKeyPool selectApiKeyPoolByKeyId(Long keyId);

    /**
     * 查询API Key池列表
     * 
     * @param apiKeyPool API Key池
     * @return API Key池集合
     */
    public List<ApiKeyPool> selectApiKeyPoolList(ApiKeyPool apiKeyPool);

    /**
     * 新增API Key池
     * 
     * @param apiKeyPool API Key池
     * @return 结果
     */
    public int insertApiKeyPool(ApiKeyPool apiKeyPool);

    /**
     * 修改API Key池
     * 
     * @param apiKeyPool API Key池
     * @return 结果
     */
    public int updateApiKeyPool(ApiKeyPool apiKeyPool);

    /**
     * 批量删除API Key池
     * 
     * @param keyIds 需要删除的API Key池主键集合
     * @return 结果
     */
    public int deleteApiKeyPoolByKeyIds(Long[] keyIds);

    /**
     * 删除API Key池信息
     * 
     * @param keyId API Key池主键
     * @return 结果
     */
    public int deleteApiKeyPoolByKeyId(Long keyId);

    /**
     * 获取单个可用Key（智能负载均衡）
     * 
     * @param resourceType 资源类型(ai_model/tts_engine)
     * @param resourceId 资源ID
     * @return API Key信息
     */
    public ApiKeyPool acquireKey(String resourceType, Long resourceId);

    /**
     * 获取多个可用Key（用于并行处理）
     * 
     * @param resourceType 资源类型
     * @param resourceId 资源ID
     * @param count 需要的Key数量
     * @return Key列表（实际可能少于count）
     */
    public List<ApiKeyPool> acquireKeys(String resourceType, Long resourceId, int count);

    /**
     * 获取跨资源的可用Key（仅用于AI翻译跨模型）
     * 
     * @param resourceIds 允许使用的资源ID列表，空=所有启用资源
     * @param count 需要的Key数量
     * @return Key列表
     */
    public List<ApiKeyPool> acquireKeysAcrossModels(List<Long> resourceIds, int count);

    /**
     * 释放Key
     * 
     * @param keyId Key ID
     */
    public void releaseKey(Long keyId);

    /**
     * 标记Key为限流状态
     * 
     * @param keyId Key ID
     * @param seconds 限流秒数
     */
    public void markRateLimited(Long keyId, int seconds);

    /**
     * 更新Key统计信息
     * 
     * @param keyId Key ID
     * @param success 是否成功
     * @param error 错误信息
     * @param responseTimeMs 响应时间(毫秒)
     */
    public void updateKeyStats(Long keyId, boolean success, String error, long responseTimeMs);

    /**
     * 恢复限流状态的Key（定时任务调用）
     * 
     * @return 恢复的Key数量
     */
    public int recoverRateLimitedKeys();
}

